背景

本 PR 当前包含两组文档收敛：

• #172：补齐共享扩展契约的文档可发现性
• #145：发布面向消费方 agent 的自部署 / 释放 SOP，并明确 deploy.sh 与 deploy_light.sh 的适用边界

本次变更仍然聚焦文档层，不引入运行时代码逻辑修改。

模块变更

README.md

• 新增 Extension Capability Overview 作为能力展示入口，集中说明 6 个 extension URI 的 shared/private 边界与主要用途
• 补充 docs/agent_deploy_sop.md 的入口，便于从仓库首页直接定位部署 SOP
• 调整 Documentation Map 文案，使 README 负责展示层，详细消费/操作说明下沉到对应文档

docs/guide.md

• 将扩展能力总览收敛为消费导向说明，明确区分 Agent Card capability declaration 与运行时 shared metadata
• 将原有会话继续说明提升为正式的 Shared Session Binding Contract 专章
• 新增 Shared Stream Hints Contract 专章
• 在 Shared Model Selection Contract 中补充 capability URI，保持 shared contract 表达一致

docs/agent_deploy_sop.md

• 将原中文 draft 升级为正式英文 SOP
• 同步项目名为 opencode-a2a-server
• 明确区分两条启动路径：
  • deploy.sh：systemd、多实例、生产导向
  • deploy_light.sh：当前用户、轻量、本地/自托管导向
• 单独说明 ENABLE_SECRET_PERSISTENCE=false 的安全默认两步流程，与 ENABLE_SECRET_PERSISTENCE=true 的显式落盘模式
• 为两条路径分别补充启动、校验、释放方式

scripts/README.md

• 增加 deploy SOP 的索引入口，补齐脚本文档与操作 SOP 的导航关系

.gitignore

• 增加 run/，避免本地运行产物持续污染工作区

相关 Commits

• docs(guide): document shared extension capability contracts (#172)
• docs(readme): surface extension capability overview (#172)
• docs(sop): draft zh-cn agent self-deploy and release guide #145
• docs(sop): publish agent self-deploy and release SOP (#145)

关联 Issues

• Closes [Priority: Med] [docs] 补齐 shared session-binding 与 stream-hints 扩展消费文档 #172
• Related [Priority: High] [Feature] 支持消费方按需自部署 opencode-a2a-server（参数化拉起） #145
• Related downstream issues:
  • [Priority: High] [Feature] 对齐 shared session-binding 契约并消费 metadata.shared.session.id liujuanjuan1984/a2a-client-hub#463
  • [Priority: Med] [Feature] 补齐 stream-hints extension 能力消费与回退策略 liujuanjuan1984/a2a-client-hub#464

验证

uv run pre-commit run --files .gitignore README.md docs/guide.md
uv run pre-commit run --files docs/agent_deploy_sop.md README.md scripts/README.md
uv run pytest

结果：

• pre-commit 通过
• pytest 167 项通过，coverage 84.48%